<!-- HTML header for doxygen 1.9.7-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<title>libsir: The Standard Incident Reporter Library</title>
<!-- OpenGraph -->
<meta property="og:title" content="libsir: The Standard Incident Reporter Library">
<meta property="og:description" content="A lightweight, cross-platform C library for information distribution">
<meta property="og:url" content="https://libsir.rml.dev">
<meta property="og:type" content="website">
<meta property="og:image" content="https://libsir.rml.dev/res/libsir-og.png">
<meta name="twitter:card" content="summary_large_image"></meta>
<meta name="twitter:title" content="libsir: The Standard Incident Reporter Library"></meta>
<meta name="twitter:description" content="A lightweight, cross-platform C library for information distribution"></meta>
<meta name="twitter:image" content="https://libsir.rml.dev/res/libsir-og.png"></meta>
<!-- /OpenGraph -->
<!-- favicon -->
<link rel="icon" href="res/libsir-icon.png">
<link rel="icon" href="res/libsir-icon.svg" type="image/svg+xml">
<link rel="manifest" href="res/icons.webmanifest">
<!-- /favicon -->
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
<link href="rml-navtree.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libsir<span id="projectnumber">&#160;2.2.6</span>
   </div>
   <div id="projectbrief">Standard Incident Reporter</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search',true);
  $(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('group__plugins.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle"><div class="title">Plugins</div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga938b693a1eae42f7d93b136b8851f176" id="r_ga938b693a1eae42f7d93b136b8851f176"><td class="memItemLeft" align="right" valign="top">PLUGIN_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga938b693a1eae42f7d93b136b8851f176">sir_plugin_query</a> (<a class="el" href="structsir__plugininfo.html">sir_plugininfo</a> *info)</td></tr>
<tr class="memdesc:ga938b693a1eae42f7d93b136b8851f176"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called by libsir after the plugin library object is loaded, but before any other functions are probed or called.  <br /></td></tr>
<tr class="separator:ga938b693a1eae42f7d93b136b8851f176"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga16ed2c82f4bf0b4571c2d79bb946ce2d" id="r_ga16ed2c82f4bf0b4571c2d79bb946ce2d"><td class="memItemLeft" align="right" valign="top">PLUGIN_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga16ed2c82f4bf0b4571c2d79bb946ce2d">sir_plugin_init</a> (void)</td></tr>
<tr class="memdesc:ga16ed2c82f4bf0b4571c2d79bb946ce2d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called by libsir after the plugin is queried and successfully validated.  <br /></td></tr>
<tr class="separator:ga16ed2c82f4bf0b4571c2d79bb946ce2d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga8bcc79c4667749f5c81e6b1f22db0f1d" id="r_ga8bcc79c4667749f5c81e6b1f22db0f1d"><td class="memItemLeft" align="right" valign="top">PLUGIN_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga8bcc79c4667749f5c81e6b1f22db0f1d">sir_plugin_write</a> (<a class="el" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c">sir_level</a> level, const char *message)</td></tr>
<tr class="memdesc:ga8bcc79c4667749f5c81e6b1f22db0f1d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called by libsir when a message is dispatched on any level whose bit was set in the <code>levels</code> bitmask of the <a class="el" href="structsir__plugininfo.html" title="The libsir-to-plugin query data structure.">sir_plugininfo</a> structure when <a class="el" href="#ga938b693a1eae42f7d93b136b8851f176" title="Called by libsir after the plugin library object is loaded, but before any other functions are probed...">sir_plugin_query</a> was called.  <br /></td></tr>
<tr class="separator:ga8bcc79c4667749f5c81e6b1f22db0f1d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga43748071f13fd42b462fab8e3ea9faef" id="r_ga43748071f13fd42b462fab8e3ea9faef"><td class="memItemLeft" align="right" valign="top">PLUGIN_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga43748071f13fd42b462fab8e3ea9faef">sir_plugin_cleanup</a> (void)</td></tr>
<tr class="memdesc:ga43748071f13fd42b462fab8e3ea9faef"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called by libsir when the plugin is about to be unloaded.  <br /></td></tr>
<tr class="separator:ga43748071f13fd42b462fab8e3ea9faef"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2>Intro</h2>
<p>Using plugins, it is possible to extend libsir's reach when dispatching log messages. A simple example of this would be a plugin that only registers for emergency-level messages. Whenever it receives a message, it posts the message to a REST API endpoint which results in a push notification being sent to a mobile device.</p>
<p>Use your imagination; essentially anything is possible. There are some caveats, though: until the thread pool and job queue mechanisms implemented in (<a href="https://github.com/aremmell/libsir/issues/121">#121</a>) are utilized, plugins must either only perform operations that are guaranteed to complete quickly, or perform those operations asynchronously (<em>i.e., on another thread</em>).</p>
<h2>Versioning</h2>
<p>libsir's plugin interface will be versioned; the functions appearing on this page comprise the plugin interface v1. If/when a new function export is added (or one is modified), the version number will be bumped.</p>
<p>When plugins are compiled, their interface version is hard-coded in. This means that as libsir continues to evolve (and the version number increases), it can still communicate with older plugins via backwards-compatible versioned interfaces.</p>
<h2>Creating your own plugin</h2>
<p>The following steps should be taken in order to write your own fully- functioning libsir plugin:</p>
<ul>
<li>Make a copy of the <code>plugins/sample</code> directory (within <code>plugins</code>).</li>
<li>Rename the new directory whatever you'd like. The name of the new directory will determine the name of the plugin file that is produced.</li>
<li>Study the implementation of the sample plugin. It is included below for your convenience. Modify your copy to suit your specific needs.</li>
</ul>
<div class="fragment"><div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> * plugin_sample.c</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * Version: 2.2.6</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * -----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * SPDX-License-Identifier: MIT</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * Copyright (c) 2018-2024 Ryan M. Lederman &lt;lederman@gmail.com&gt;</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * Permission is hereby granted, free of charge, to any person obtaining a copy of</span></div>
<div class="line"><span class="comment"> * this software and associated documentation files (the &quot;Software&quot;), to deal in</span></div>
<div class="line"><span class="comment"> * the Software without restriction, including without limitation the rights to</span></div>
<div class="line"><span class="comment"> * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of</span></div>
<div class="line"><span class="comment"> * the Software, and to permit persons to whom the Software is furnished to do so,</span></div>
<div class="line"><span class="comment"> * subject to the following conditions:</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * The above copyright notice and this permission notice shall be included in all</span></div>
<div class="line"><span class="comment"> * copies or substantial portions of the Software.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR</span></div>
<div class="line"><span class="comment"> * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS</span></div>
<div class="line"><span class="comment"> * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR</span></div>
<div class="line"><span class="comment"> * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER</span></div>
<div class="line"><span class="comment"> * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN</span></div>
<div class="line"><span class="comment"> * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</span></div>
<div class="line"><span class="comment"> *</span></div>
<div class="line"><span class="comment"> * -----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#include &quot;plugin_sample.h&quot;</span></div>
<div class="line"><span class="preprocessor">#include &quot;<a class="code" href="ansimacros_8h.html">sir/ansimacros.h</a>&quot;</span></div>
<div class="line"><span class="preprocessor">#include &quot;sir/helpers.h&quot;</span></div>
<div class="line"><span class="preprocessor">#include &lt;stdio.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#if defined(__WIN__)</span></div>
<div class="line">BOOL APIENTRY DllMain(HMODULE module, DWORD ul_reason_for_call, LPVOID reserved) {</div>
<div class="line">    SIR_UNUSED(module);</div>
<div class="line">    SIR_UNUSED(ul_reason_for_call);</div>
<div class="line">    SIR_UNUSED(reserved);</div>
<div class="line">    <span class="keywordflow">return</span> TRUE;</div>
<div class="line">}</div>
<div class="line"><span class="preprocessor">#endif</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> uint8_t maj_ver   = 1U;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> uint8_t min_ver   = 0U;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> uint8_t bld_ver   = 0U;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <a class="code hl_typedef" href="group__publictypes.html#ga7ee5f2908abd2df9e89bcab0b6608edd">sir_levels</a> levels = <a class="code hl_define" href="group__publictypes.html#gaa2927c260f1d8fac96513442e50105fc">SIRL_DEBUG</a> | <a class="code hl_define" href="group__publictypes.html#ga9e73defcee82050f038956ad7e911621">SIRL_INFO</a>;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <a class="code hl_typedef" href="group__publictypes.html#gafb659914aac0129182d86f7d3414e85d">sir_options</a> opts  = <a class="code hl_define" href="group__publictypes.html#gaf6a215c540807f3ba15f97d372feeaf0">SIRO_NOHOST</a> | <a class="code hl_define" href="group__publictypes.html#ga093cea38ace2acb674162a0f7fb153a6">SIRO_NOTID</a>;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">char</span>* author      = <span class="stringliteral">&quot;libsir contributors&quot;</span>;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">char</span>* desc        = <span class="stringliteral">&quot;Logs messages and function calls to stdout.&quot;</span>;</div>
<div class="line"><span class="keyword">static</span> <span class="keyword">const</span> uint64_t caps     = 0ULL;</div>
<div class="line"> </div>
<div class="line">PLUGIN_EXPORT <span class="keywordtype">bool</span> <a class="code hl_function" href="#ga938b693a1eae42f7d93b136b8851f176">sir_plugin_query</a>(<a class="code hl_struct" href="structsir__plugininfo.html">sir_plugininfo</a>* info) {</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#a125b2cde17902e0d197fa3157337f3ae">iface_ver</a> = SIR_PLUGIN_VCURRENT;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#ada7d4dcf686295a51247716ed20b36be">maj_ver</a>   = maj_ver;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#a71e87991b1776d2a9346598ceebf1f1a">min_ver</a>   = min_ver;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#a430d916d71dd58f9909348181c98751b">bld_ver</a>   = bld_ver;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#ab3d8e14fb3f09579052cfc6f48e638b7">levels</a>    = levels;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#af8690ae21184c15db2a8a93655d3a516">opts</a>      = opts;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#ab10ea6843c9f67e861b2f8410119022f">author</a>    = author;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#aa52c4fcccd437ab1a4349bd8e6f64922">desc</a>      = desc;</div>
<div class="line">    info-&gt;<a class="code hl_variable" href="structsir__plugininfo.html#a92d9ff1c0c4764f1e066a24efecebfd0">caps</a>      = caps;</div>
<div class="line"> </div>
<div class="line">    (void)printf(<span class="stringliteral">&quot;\t&quot;</span> <a class="code hl_define" href="ansimacros_8h.html#a431770ad1899e2c03d8b005c1eadaee2">SIR_DGRAY</a>(<span class="stringliteral">&quot;plugin_sample (&#39;%s&#39;)&quot;</span>) <a class="code hl_define" href="config_8h.html#a1cd3bda6ec91d6c0b14b352aa40344d5">SIR_EOL</a>, __func__);</div>
<div class="line">    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">PLUGIN_EXPORT <span class="keywordtype">bool</span> <a class="code hl_function" href="#ga16ed2c82f4bf0b4571c2d79bb946ce2d">sir_plugin_init</a>(<span class="keywordtype">void</span>) {</div>
<div class="line">    (void)printf(<span class="stringliteral">&quot;\t&quot;</span> <a class="code hl_define" href="ansimacros_8h.html#a431770ad1899e2c03d8b005c1eadaee2">SIR_DGRAY</a>(<span class="stringliteral">&quot;plugin_sample (&#39;%s&#39;)&quot;</span>) <a class="code hl_define" href="config_8h.html#a1cd3bda6ec91d6c0b14b352aa40344d5">SIR_EOL</a>, __func__);</div>
<div class="line">    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">PLUGIN_EXPORT <span class="keywordtype">bool</span> <a class="code hl_function" href="#ga8bcc79c4667749f5c81e6b1f22db0f1d">sir_plugin_write</a>(<a class="code hl_typedef" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c">sir_level</a> level, <span class="keyword">const</span> <span class="keywordtype">char</span>* message) {</div>
<div class="line">    (void)printf(<span class="stringliteral">&quot;\t&quot;</span> <a class="code hl_define" href="ansimacros_8h.html#a431770ad1899e2c03d8b005c1eadaee2">SIR_DGRAY</a>(<span class="stringliteral">&quot;plugin_sample (%s): level: %04&quot;</span>PRIx16<span class="stringliteral">&quot;, message: %s&quot;</span>) <a class="code hl_define" href="config_8h.html#a1cd3bda6ec91d6c0b14b352aa40344d5">SIR_EOL</a>,</div>
<div class="line">                 __func__, level, message);</div>
<div class="line">    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">PLUGIN_EXPORT <span class="keywordtype">bool</span> <a class="code hl_function" href="#ga43748071f13fd42b462fab8e3ea9faef">sir_plugin_cleanup</a>(<span class="keywordtype">void</span>) { <span class="comment">//-V524</span></div>
<div class="line">    (void)printf(<span class="stringliteral">&quot;\t&quot;</span> <a class="code hl_define" href="ansimacros_8h.html#a431770ad1899e2c03d8b005c1eadaee2">SIR_DGRAY</a>(<span class="stringliteral">&quot;plugin_sample (&#39;%s&#39;)&quot;</span>) <a class="code hl_define" href="config_8h.html#a1cd3bda6ec91d6c0b14b352aa40344d5">SIR_EOL</a>, __func__);</div>
<div class="line">    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
<div class="ttc" id="aansimacros_8h_html"><div class="ttname"><a href="ansimacros_8h.html">ansimacros.h</a></div><div class="ttdoc">ANSI escape sequence macros.</div></div>
<div class="ttc" id="aansimacros_8h_html_a431770ad1899e2c03d8b005c1eadaee2"><div class="ttname"><a href="ansimacros_8h.html#a431770ad1899e2c03d8b005c1eadaee2">SIR_DGRAY</a></div><div class="ttdeci">#define SIR_DGRAY(s)</div><div class="ttdoc">Dark gray foreground text.</div><div class="ttdef"><b>Definition</b> ansimacros.h:131</div></div>
<div class="ttc" id="aconfig_8h_html_a1cd3bda6ec91d6c0b14b352aa40344d5"><div class="ttname"><a href="config_8h.html#a1cd3bda6ec91d6c0b14b352aa40344d5">SIR_EOL</a></div><div class="ttdeci">#define SIR_EOL</div><div class="ttdoc">The end of line sequence.</div><div class="ttdef"><b>Definition</b> config.h:91</div></div>
<div class="ttc" id="agroup__plugins_html_ga16ed2c82f4bf0b4571c2d79bb946ce2d"><div class="ttname"><a href="#ga16ed2c82f4bf0b4571c2d79bb946ce2d">sir_plugin_init</a></div><div class="ttdeci">PLUGIN_EXPORT bool sir_plugin_init(void)</div><div class="ttdoc">Called by libsir after the plugin is queried and successfully validated.</div><div class="ttdef"><b>Definition</b> plugin_sample.c:70</div></div>
<div class="ttc" id="agroup__plugins_html_ga43748071f13fd42b462fab8e3ea9faef"><div class="ttname"><a href="#ga43748071f13fd42b462fab8e3ea9faef">sir_plugin_cleanup</a></div><div class="ttdeci">PLUGIN_EXPORT bool sir_plugin_cleanup(void)</div><div class="ttdoc">Called by libsir when the plugin is about to be unloaded.</div><div class="ttdef"><b>Definition</b> plugin_sample.c:81</div></div>
<div class="ttc" id="agroup__plugins_html_ga8bcc79c4667749f5c81e6b1f22db0f1d"><div class="ttname"><a href="#ga8bcc79c4667749f5c81e6b1f22db0f1d">sir_plugin_write</a></div><div class="ttdeci">PLUGIN_EXPORT bool sir_plugin_write(sir_level level, const char *message)</div><div class="ttdoc">Called by libsir when a message is dispatched on any level whose bit was set in the levels bitmask of...</div><div class="ttdef"><b>Definition</b> plugin_sample.c:75</div></div>
<div class="ttc" id="agroup__plugins_html_ga938b693a1eae42f7d93b136b8851f176"><div class="ttname"><a href="#ga938b693a1eae42f7d93b136b8851f176">sir_plugin_query</a></div><div class="ttdeci">PLUGIN_EXPORT bool sir_plugin_query(sir_plugininfo *info)</div><div class="ttdoc">Called by libsir after the plugin library object is loaded, but before any other functions are probed...</div><div class="ttdef"><b>Definition</b> plugin_sample.c:55</div></div>
<div class="ttc" id="agroup__publictypes_html_ga076e759e9aa36cde2977f754a7ea186c"><div class="ttname"><a href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c">sir_level</a></div><div class="ttdeci">uint16_t sir_level</div><div class="ttdoc">The sir_level type.</div><div class="ttdef"><b>Definition</b> types.h:71</div></div>
<div class="ttc" id="agroup__publictypes_html_ga093cea38ace2acb674162a0f7fb153a6"><div class="ttname"><a href="group__publictypes.html#ga093cea38ace2acb674162a0f7fb153a6">SIRO_NOTID</a></div><div class="ttdeci">#define SIRO_NOTID</div><div class="ttdoc">Exclude thread ID/name.</div><div class="ttdef"><b>Definition</b> types.h:87</div></div>
<div class="ttc" id="agroup__publictypes_html_ga7ee5f2908abd2df9e89bcab0b6608edd"><div class="ttname"><a href="group__publictypes.html#ga7ee5f2908abd2df9e89bcab0b6608edd">sir_levels</a></div><div class="ttdeci">uint16_t sir_levels</div><div class="ttdoc">sir_level bitmask type.</div><div class="ttdef"><b>Definition</b> types.h:74</div></div>
<div class="ttc" id="agroup__publictypes_html_ga9e73defcee82050f038956ad7e911621"><div class="ttname"><a href="group__publictypes.html#ga9e73defcee82050f038956ad7e911621">SIRL_INFO</a></div><div class="ttdeci">#define SIRL_INFO</div><div class="ttdoc">Informational messages.</div><div class="ttdef"><b>Definition</b> types.h:65</div></div>
<div class="ttc" id="agroup__publictypes_html_gaa2927c260f1d8fac96513442e50105fc"><div class="ttname"><a href="group__publictypes.html#gaa2927c260f1d8fac96513442e50105fc">SIRL_DEBUG</a></div><div class="ttdeci">#define SIRL_DEBUG</div><div class="ttdoc">Debugging/diagnostic output.</div><div class="ttdef"><b>Definition</b> types.h:66</div></div>
<div class="ttc" id="agroup__publictypes_html_gaf6a215c540807f3ba15f97d372feeaf0"><div class="ttname"><a href="group__publictypes.html#gaf6a215c540807f3ba15f97d372feeaf0">SIRO_NOHOST</a></div><div class="ttdeci">#define SIRO_NOHOST</div><div class="ttdoc">Exclude local hostname.</div><div class="ttdef"><b>Definition</b> types.h:83</div></div>
<div class="ttc" id="agroup__publictypes_html_gafb659914aac0129182d86f7d3414e85d"><div class="ttname"><a href="group__publictypes.html#gafb659914aac0129182d86f7d3414e85d">sir_options</a></div><div class="ttdeci">uint32_t sir_options</div><div class="ttdoc">sir_option bitmask type.</div><div class="ttdef"><b>Definition</b> types.h:96</div></div>
<div class="ttc" id="astructsir__plugininfo_html"><div class="ttname"><a href="structsir__plugininfo.html">sir_plugininfo</a></div><div class="ttdoc">The libsir-to-plugin query data structure.</div><div class="ttdef"><b>Definition</b> types.h:329</div></div>
<div class="ttc" id="astructsir__plugininfo_html_a125b2cde17902e0d197fa3157337f3ae"><div class="ttname"><a href="structsir__plugininfo.html#a125b2cde17902e0d197fa3157337f3ae">sir_plugininfo::iface_ver</a></div><div class="ttdeci">uint8_t iface_ver</div><div class="ttdoc">Plugin interface version.</div><div class="ttdef"><b>Definition</b> types.h:330</div></div>
<div class="ttc" id="astructsir__plugininfo_html_a430d916d71dd58f9909348181c98751b"><div class="ttname"><a href="structsir__plugininfo.html#a430d916d71dd58f9909348181c98751b">sir_plugininfo::bld_ver</a></div><div class="ttdeci">uint8_t bld_ver</div><div class="ttdoc">Build/patch version number.</div><div class="ttdef"><b>Definition</b> types.h:333</div></div>
<div class="ttc" id="astructsir__plugininfo_html_a71e87991b1776d2a9346598ceebf1f1a"><div class="ttname"><a href="structsir__plugininfo.html#a71e87991b1776d2a9346598ceebf1f1a">sir_plugininfo::min_ver</a></div><div class="ttdeci">uint8_t min_ver</div><div class="ttdoc">Minor version number.</div><div class="ttdef"><b>Definition</b> types.h:332</div></div>
<div class="ttc" id="astructsir__plugininfo_html_a92d9ff1c0c4764f1e066a24efecebfd0"><div class="ttname"><a href="structsir__plugininfo.html#a92d9ff1c0c4764f1e066a24efecebfd0">sir_plugininfo::caps</a></div><div class="ttdeci">uint64_t caps</div><div class="ttdoc">Plugin capabilities bitmask.</div><div class="ttdef"><b>Definition</b> types.h:338</div></div>
<div class="ttc" id="astructsir__plugininfo_html_aa52c4fcccd437ab1a4349bd8e6f64922"><div class="ttname"><a href="structsir__plugininfo.html#aa52c4fcccd437ab1a4349bd8e6f64922">sir_plugininfo::desc</a></div><div class="ttdeci">const char * desc</div><div class="ttdoc">Plugin description.</div><div class="ttdef"><b>Definition</b> types.h:337</div></div>
<div class="ttc" id="astructsir__plugininfo_html_ab10ea6843c9f67e861b2f8410119022f"><div class="ttname"><a href="structsir__plugininfo.html#ab10ea6843c9f67e861b2f8410119022f">sir_plugininfo::author</a></div><div class="ttdeci">const char * author</div><div class="ttdoc">Plugin author information.</div><div class="ttdef"><b>Definition</b> types.h:336</div></div>
<div class="ttc" id="astructsir__plugininfo_html_ab3d8e14fb3f09579052cfc6f48e638b7"><div class="ttname"><a href="structsir__plugininfo.html#ab3d8e14fb3f09579052cfc6f48e638b7">sir_plugininfo::levels</a></div><div class="ttdeci">sir_levels levels</div><div class="ttdoc">Level registration bitmask.</div><div class="ttdef"><b>Definition</b> types.h:334</div></div>
<div class="ttc" id="astructsir__plugininfo_html_ada7d4dcf686295a51247716ed20b36be"><div class="ttname"><a href="structsir__plugininfo.html#ada7d4dcf686295a51247716ed20b36be">sir_plugininfo::maj_ver</a></div><div class="ttdeci">uint8_t maj_ver</div><div class="ttdoc">Major version number.</div><div class="ttdef"><b>Definition</b> types.h:331</div></div>
<div class="ttc" id="astructsir__plugininfo_html_af8690ae21184c15db2a8a93655d3a516"><div class="ttname"><a href="structsir__plugininfo.html#af8690ae21184c15db2a8a93655d3a516">sir_plugininfo::opts</a></div><div class="ttdeci">sir_options opts</div><div class="ttdoc">Formatting options bitmask.</div><div class="ttdef"><b>Definition</b> types.h:335</div></div>
</div><!-- fragment --><ul>
<li><code>cd</code> back into the root directory of the repository and run <code>make clean plugins</code>. If everything goes smoothly, your shiny new plugin should now be located in <code>build/lib</code>. If you named your directory 'foo', you should see a <code>plugin_foo.[so/dll]</code>.</li>
<li>You can now move the plugin wherever you'd like, and use <a class="el" href="group__publicfuncs.html#ga1a50b52b3ce1af7543b76a219ff01060" title="Loads a plugin module from disk.">sir_loadplugin</a> to load it (after you've called <a class="el" href="group__publicfuncs.html#gaa4f5707f5e4ed9702cde75a8c80c4e4a" title="Initializes libsir for use.">sir_init</a>, of course).</li>
</ul>
<p>If you encounter any problems, rebuild with <code>env SIR_SELFLOG=1 SIR_DEBUG=1 make clean plugins</code>. This will enable diagnostic output from libsir that should aid in the diagnosis of any issues you encounter. If you're still stuck, <a href="https://github.com/aremmell/libsir/discussions/new?category=q-a">reach out</a> and somebody will assist you within a reasonable amount of time. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga43748071f13fd42b462fab8e3ea9faef" name="ga43748071f13fd42b462fab8e3ea9faef"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga43748071f13fd42b462fab8e3ea9faef">&#9670;&#160;</a></span>sir_plugin_cleanup()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">PLUGIN_EXPORT bool sir_plugin_cleanup </td>
          <td>(</td>
          <td class="paramtype">void</td>          <td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Called by libsir when the plugin is about to be unloaded. </p>
<p>The plugin should immediately begin releasing allocated resources and resetting its internal state.</p>
<dl class="section return"><dt>Returns</dt><dd>bool <code>true</code> if the plugin cleaned up successfully, <code>false</code> otherwise. </dd></dl>

</div>
</div>
<a id="ga16ed2c82f4bf0b4571c2d79bb946ce2d" name="ga16ed2c82f4bf0b4571c2d79bb946ce2d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga16ed2c82f4bf0b4571c2d79bb946ce2d">&#9670;&#160;</a></span>sir_plugin_init()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">PLUGIN_EXPORT bool sir_plugin_init </td>
          <td>(</td>
          <td class="paramtype">void</td>          <td class="paramname"><span class="paramname"><em></em></span></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Called by libsir after the plugin is queried and successfully validated. </p>
<p>The plugin should only at the time of this call begin allocating resources and initializing its internal state.</p>
<dl class="section return"><dt>Returns</dt><dd>bool <code>true</code> if the plugin successfully initialized its internal state, <code>false</code> otherwise. </dd></dl>

</div>
</div>
<a id="ga938b693a1eae42f7d93b136b8851f176" name="ga938b693a1eae42f7d93b136b8851f176"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga938b693a1eae42f7d93b136b8851f176">&#9670;&#160;</a></span>sir_plugin_query()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">PLUGIN_EXPORT bool sir_plugin_query </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structsir__plugininfo.html">sir_plugininfo</a> *</td>          <td class="paramname"><span class="paramname"><em>info</em></span></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Called by libsir after the plugin library object is loaded, but before any other functions are probed or called. </p>
<p>The plugin must fill out the information in the <code>info</code> structure in a way satisfactory to libsir, or it will immediately be unloaded:</p>
<ul>
<li>all members of the <a class="el" href="structsir__plugininfo.html" title="The libsir-to-plugin query data structure.">sir_plugininfo</a> structure are required to be set by the plugin.</li>
<li><code>iface_ver</code> must be set to <code>SIR_PLUGIN_VCURRENT</code>.</li>
<li><code>char*</code> members must be set to valid strings, and must point at static memory that will not go out of scope when the function exits. Do not allocate heap memory for these properties; they will be leaked.</li>
<li><code>levels</code> must be a valid <a class="el" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c" title="The sir_level type.">sir_level</a> bitmask.</li>
<li><code>opts</code> must be a valid <a class="el" href="group__publictypes.html#gac28da6e48402cc15ead5b5384bccb6fd" title="The sir_option type.">sir_option</a> bitmask.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>It is not possible to change these settings once chosen, so ensure that they are correct.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c" title="The sir_level type.">sir_level</a> </dd>
<dd>
<a class="el" href="group__publictypes.html#gac28da6e48402cc15ead5b5384bccb6fd" title="The sir_option type.">sir_option</a> </dd>
<dd>
<a class="el" href="group__default.html" title="Default sir_option bitmasks, sir_level registrations, and sir_textstyle bitmasks.">Defaults</a></dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">info</td><td>Pointer to a <a class="el" href="structsir__plugininfo.html" title="The libsir-to-plugin query data structure.">sir_plugininfo</a> structure to be initialized by the plugin. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>bool <code>true</code> if the <code>info</code> structure was successfully initialized, <code>false</code> otherwise. If <code>false</code>, the plugin will be unloaded. </dd></dl>

</div>
</div>
<a id="ga8bcc79c4667749f5c81e6b1f22db0f1d" name="ga8bcc79c4667749f5c81e6b1f22db0f1d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8bcc79c4667749f5c81e6b1f22db0f1d">&#9670;&#160;</a></span>sir_plugin_write()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">PLUGIN_EXPORT bool sir_plugin_write </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c">sir_level</a></td>          <td class="paramname"><span class="paramname"><em>level</em></span>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char *</td>          <td class="paramname"><span class="paramname"><em>message</em></span>&#160;)</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Called by libsir when a message is dispatched on any level whose bit was set in the <code>levels</code> bitmask of the <a class="el" href="structsir__plugininfo.html" title="The libsir-to-plugin query data structure.">sir_plugininfo</a> structure when <a class="el" href="#ga938b693a1eae42f7d93b136b8851f176" title="Called by libsir after the plugin library object is loaded, but before any other functions are probed...">sir_plugin_query</a> was called. </p>
<p>The <code>message</code> string will be pre-formatted according to the <a class="el" href="group__publictypes.html#gac28da6e48402cc15ead5b5384bccb6fd" title="The sir_option type.">sir_option</a> set in the <code>opts</code> bitmask of the <a class="el" href="structsir__plugininfo.html" title="The libsir-to-plugin query data structure.">sir_plugininfo</a> structure.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">level</td><td>The <a class="el" href="group__publictypes.html#ga076e759e9aa36cde2977f754a7ea186c" title="The sir_level type.">sir_level</a> of the message being dispatched. </td></tr>
    <tr><td class="paramname">message</td><td>A string containing the pre-formatted message being dispatched. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>bool <code>true</code> if the message was successfully processed, <code>false</code> otherwise. </dd></dl>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.7-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
  </ul>
</div>
</body>
</html>
